package com.smart.community.region.service;

import java.util.List;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.region.dto.HouseholdDTO;
import com.smart.community.region.dto.HouseholdQueryDTO;
import com.smart.community.region.dto.HouseholdUpdateDTO;
import com.smart.community.region.entity.Household;
import com.smart.community.region.entity.Unit;
import com.smart.community.region.vo.HouseholdDeleteImpactVO;
import com.smart.community.commons.exception.BusinessException;

/**
 * 住户管理服务接口
 *
 * @author Wu.Liang
 * @since 2024-12-21
 */
public interface IHouseholdService extends IService<Household> {

	// ==================== 基础CRUD方法 ====================

	/**
	 * 分页查询住户列表
	 *
	 * @param queryDTO 查询条件
	 * @return 分页结果
	 */
	IPage<Household> getHouseholdPage(HouseholdQueryDTO queryDTO) throws Exception;

	/**
	 * 获取住户详情
	 *
	 * @param householdId 住户ID
	 * @return 住户详情
	 */
	Household getHouseholdDetail(Long householdId) throws Exception;

	/**
	 * 根据编码查询住户
	 *
	 * @param householdCode 住户编码
	 * @return 住户信息
	 */
	Household getHouseholdByCode(String householdCode) throws Exception;

	/**
	 * 创建住户
	 *
	 * @param householdDTO 住户信息
	 * @return 是否成功
	 */
	boolean createHousehold(HouseholdDTO householdDTO) throws Exception;

	/**
	 * 更新住户
	 *
	 * @param householdDTO 住户信息
	 * @return 是否成功
	 */
	boolean updateHousehold(HouseholdDTO householdDTO) throws Exception;

	/**
	 * 更新住户（使用专门的更新DTO）
	 *
	 * @param householdUpdateDTO 住户更新信息
	 * @return 是否成功
	 */
	boolean updateHousehold(HouseholdUpdateDTO householdUpdateDTO) throws Exception;

	/**
	 * 删除住户
	 *
	 * @param householdId 住户ID
	 * @return 是否成功
	 */
	boolean deleteHousehold(Long householdId) throws Exception;

	/**
	 * 批量删除住户
	 *
	 * @param householdIds 住户ID列表
	 * @return 是否成功
	 */
	boolean batchDeleteHouseholds(List<Long> householdIds) throws Exception;

	// ==================== 查询方法 ====================

	/**
	 * 根据楼栋获取住户列表
	 *
	 * @param buildingId 楼栋ID
	 * @return 住户列表
	 */
	List<Household> getHouseholdsByBuilding(Long buildingId) throws Exception;

	/**
	 * 根据社区获取住户列表
	 *
	 * @param communityId 社区ID
	 * @return 住户列表
	 */
	List<Household> getHouseholdsByCommunity(Long communityId) throws Exception;

	/**
	 * 根据单元ID查询住户列表
	 *
	 * @param unitId 单元ID
	 * @return 住户列表
	 */
	List<Household> getHouseholdByUnitId(Long unitId) throws Exception;

	/**
	 * 根据社区ID批量查询住户，支持按单元分组返回和状态过滤
	 *
	 * @param communityIds 社区ID列表
	 * @param unitIds      单元ID列表
	 * @param status       状态
	 * @return 住户列表
	 */
	List<Household> getHouseholdsGroupedByUnit(List<Long> communityIds, List<Long> unitIds, Integer status)
			throws Exception;

	/**
	 * 根据社区ID批量查询住户
	 *
	 * @param communityIds 社区ID列表
	 * @param unitIds      单元ID列表
	 * @param status       状态
	 * @return 住户列表
	 */
	List<Household> getHouseholdsByCommunityIds(List<Long> communityIds, List<Long> unitIds, Integer status)
			throws Exception;

	// ==================== 状态管理方法 ====================

	/**
	 * 更新住户状态
	 *
	 * @param householdId 住户ID
	 * @param status      状态
	 * @return 是否成功
	 */
	boolean updateHouseholdStatus(Long householdId, Integer status) throws Exception;

	/**
	 * 批量更新住户状态
	 *
	 * @param householdIds 住户ID列表
	 * @param status       状态
	 * @return 是否成功
	 */
	boolean batchUpdateHouseholdStatus(List<Long> householdIds, Integer status) throws Exception;

	/**
	 * 批量更新住户户型
	 *
	 * @param householdIds 住户ID列表
	 * @param houseTypeId  户型ID
	 * @return 是否成功
	 */
	boolean batchUpdateHouseholdHouseType(List<Long> householdIds, Long houseTypeId) throws Exception;

	// ==================== 统计方法 ====================

	/**
	 * 获取住户统计信息
	 *
	 * @param householdId 住户ID
	 * @return 统计信息
	 */
	Object getHouseholdStats(Long householdId) throws Exception;

	/**
	 * 获取社区入住率统计
	 *
	 * @param communityId 社区ID
	 * @return 入住率统计
	 */
	Object getCommunityOccupancyStats(Long communityId) throws Exception;

	// ==================== 验证方法 ====================

	/**
	 * 检查住户编码唯一性
	 *
	 * @param householdCode      住户编码
	 * @param excludeHouseholdId 排除的住户ID
	 * @return 是否唯一
	 */
	boolean checkHouseholdCodeUnique(String householdCode, Long excludeHouseholdId) throws Exception;

	/**
	 * 统计住户数量
	 *
	 * @param unitId 单元ID（可选）
	 * @return 住户数量
	 */
	Long countHouseholds(Long unitId) throws Exception;

	// ==================== 缓存方法 ====================

	/**
	 * 清除住户缓存
	 *
	 * @param householdId 住户ID
	 */
	void clearHouseholdCache(Long householdId) throws Exception;

	/**
	 * 清除所有住户缓存
	 */
	void clearAllHouseholdCache() throws Exception;

	// ==================== 数据权限业务接口 ====================

	/**
	 * 根据单元ID集合获取房户ID集合 供其他模块调用，用于数据权限查询
	 * 
	 * @param unitIds 单元ID集合
	 * @return 房户ID集合
	 */
	List<Long> getHouseholdIdsByUnitIds(List<Long> unitIds) throws Exception;

	/**
	 * 根据房户ID集合获取用户ID集合 供其他模块调用，用于数据权限查询
	 * 
	 * @param householdIds 房户ID集合
	 * @return 用户ID集合
	 */
	List<Long> getUserIdsByHouseholdIds(List<Long> householdIds) throws Exception;

	/**
	 * 根据单元ID获取房户ID列表 供其他模块调用，用于数据权限查询
	 * 
	 * @param unitId 单元ID
	 * @return 房户ID列表
	 */
	List<Long> getHouseholdIdsByUnitId(Long unitId) throws Exception;

	/**
	 * 根据社区ID集合获取房户ID集合
	 * 用于业主统计功能，获取指定社区下的所有房户ID
	 * 
	 * @param communityIds 社区ID列表
	 * @return 房户ID列表
	 */
	List<Long> getHouseholdIdsByCommunityIds(List<Long> communityIds) throws Exception;

	// ==================== 房户生成方法 ====================

	/**
	 * 为单元批量生成房户记录 根据楼栋的楼层数和每层户数自动生成房户数据
	 * 
	 * @param unit        单元对象
	 * @param buildingId    楼栋ID
	 * @param floorCount    楼层数
	 * @param unitsPerFloor 每层户数
	 * @return 生成的房户数量
	 */
	int generateHouseholdsForUnit(Unit unit, Long buildingId, Integer floorCount, Integer unitsPerFloor)
			throws Exception;

	/**
	 * 更新单元的房户记录 根据楼层数和每层户数变化动态调整房户记录
	 * 
	 * @param unitId        单元ID
	 * @param buildingId    楼栋ID
	 * @param floorCount    楼层数
	 * @param unitsPerFloor 每层户数
	 * @return 更新的房户数量
	 */
	int updateHouseholdsForUnit(Long unitId, Long buildingId, Integer floorCount, Integer unitsPerFloor)
			throws Exception;

    /**
     * 删除房户（带关联处理）
     * 
     * @param householdId 房户ID
     * @param currentUserId 当前用户ID
     * @return 删除结果
     * @throws BusinessException 业务异常
     */
    String deleteHouseholdWithRelations(Long householdId, Long currentUserId) throws BusinessException;

    /**
     * 批量删除房户（带关联处理）
     * 
     * @param householdIds 房户ID列表
     * @param currentUserId 当前用户ID
     * @return 删除结果
     * @throws BusinessException 业务异常
     */
    String batchDeleteHouseholdsWithRelations(List<Long> householdIds, Long currentUserId) throws BusinessException;

    /**
     * 检查删除影响
     * 
     * @param householdId 房户ID
     * @return 删除影响分析
     */
    HouseholdDeleteImpactVO checkDeleteImpact(Long householdId);

}
